Import (without approval)

To import structured threat data (observables) into ThreatStream, without requiring approval of the imported data through the ThreatStream UI. Data payload must be specified in a valid JSON format that adheres to the guidelines in this article. JSON can be specified in a file or as a JSON object in your API request. When you import observables through the Import (without approval) API, no import session is created on the ThreatStream UI.

Request

/api/v2/intelligence/

HTTP Method: PATCH

The Import (without approval) API requires that you specify payload in JSON format. It has two properties: meta—for specifying global settings which apply to all observables—and objects—which specify settings per observable.

Specifying global settings is not mandatory. Per observable settings take precedent over global settings in cases where both are specified for a given attribute. For example, if classification=private in the meta section, and an imported observable has classification=public at the object level, the indicator will be marked public.

Meta Attributes

The following table lists the attributes that can be specified only in the meta section.

Attribute	Type	Description
allow_unresolved	boolean	When set to true, domain observables included in the file which do not resolve will be accepted as valid in ThreatStream and imported. Note: If allow_unresolved is not set to true, unresolved domains are always ignored.
ignore_url_host_whitelists	boolean	When set to true, all global whitelist checks on the host part of the URL will be ignored. By default, the attribute is set to false.
ignore_whitelist	boolean	When set to true, all global whitelist checks of domains, IPs, and emails will be ignored. By default, the attribute is set to false.

Shared Attributes

The attributes in the table below can be used to specify settings in the metaorobjects section of the JSON file.

Attribute	Type	Description
classification	string	Classification (visibility) of the indicator—public or private. Default: public
confidence	numeric	Confidence score that you (the source) want to assign to the imported observable(s) based on the level of confidence you have about the maliciousness of the observable. Confidence score can range from 0-100, in increasing order of confidence. If you want ThreatStream to use the confidence value that you specify and not re-assess the value using its machine-learning algorithms, seesource_confidence_weight. Note:ThreatStream only scores domain, IP, and URL observables. For all other observable types, you must specify a confidence value—either globally or per observable.
source_confidence_weight	numeric	Specifies the ratio between the amount of the source confidence of each observable and the Anomali's confidence. For example, if this setting = 30%, when calculating the final confidence, 30% weight is given to the confidence specified by the source of the observable and 70% weight is given to the confidence deemed by ThreatStream (based on the machine-learning algorithms). Notes: To use your source's confidence entirely, set source_confidence_weight to 100. source_confidence_weight can only be specified as a request attribute. It cannot be specified in the structured CSV file. In ThreatStream API, you can set the source confidence weight granularly, from 0 to 100 using the source_confidence_weight attribute. This setting only applies to observables for which classification is set to private, including those shared with trusted circles. This is the same setting as the Override System Confidence setting in ThreatStream UI (in Imports and Feeds). When this setting is unchecked, source_confidence_weight is set to 0, meaning do not use source-reported confidence value. When this setting is checked, source_confidence_weight is set to 100, meaning only use the source-reported confidence value—do not reassess the score using the machine-learning algorithms. Note: You cannot set this attribute granularly through the UI. You can only set this attribute to 0 or 100 through the UI.
expiration_ts	date	Time stamp of when intelligence will expire on ThreatStream, in ISO format. For example, 2017-01-26T00:00:00. By default, UTC time is used. You can specify your local time by appending your timezone to the value. For example, to specify PST: 2019-04-28T14:00:00-08:00 If a global or a local value is not specified for this attribute, by default 90 days is configured.
remote_api (for ThreatStream OnPrem only)	boolean	Whether intelligence is remote (stored on Cloud). This attribute does not need to be set to ingest local intelligence. Only use this attribute when ingesting remote intelligence from ThreatStream Cloud. Set this attribute to true in this case. Do not set this attribute to false for ingesting local intelligence. Doing so will generate errors.
severity	string	Severity you want to assign to the observable when it is imported. Possible values: low, medium, high, very-high Default severity values are assigned based on the indicator type of the observable.
source_feed_id	numeric	ID of a source feed.
source_locations	list of strings	Source locations assigned to the imported observables. Possible values include letter codes of regions, countries, and administrative areas (US States and Washington DC only) as defined by STIX 2.1. For example, eastern-africa, central-asia, europe, africa, NL, GB, US-FL, and US-MO.
tags	string	Tags applied to the imported observables. Tags must be specified as follows: tags: [{"name": "my_tag","tlp": "red"},{"name": "my_tag2","tlp": "clear"},{"name": "my_tag3"}] Tag Attributes: name—name of the tag that you want to add. tlp—the visibility setting for the tag. Possible values: red, amber, amber+strict, green, clear. red—private, or visible to your organization only. white—public, or visible to all ThreatStream users with access to the data. Default: white. Note: Adding public tags may be restricted by your Organization Administrator. In the example above, my_tag is private and my_tag2 and my_tag3 are public.
target_industry	list of strings	Target industries assigned to the imported observables. Possible values are defined by the STIX 2.1 Industry Sector vocabulary. For example, chemical, financial-services, and government-regional.
target_locations	list of strings	Target locations assigned to the imported observables. Possible values include letter codes of regions, countries, and administrative areas (US States and Washington DC only) as defined by STIX 2.1. For example, eastern-africa, central-asia, europe, africa, NL, GB, US-FL, and US-MO.
trustedcircles	list	ID of the trusted circle with which this threat data should be shared. If you want to import the threat data to multiple trusted circles, enter a list of comma-separated IDs. Tip: To find the ID of a trusted circle, locate the trusted circle on ThreatStream, click on its name. The URL displayed in the address bar shows the ID. For example, https://ui.threatstream.com/search?trustedcircles=13.

Required Fields

Fields which must contain data vary based on the type of observable. The following table lists the mandatory fields for each observable type.

Observable Type	Required Fields
Domain	domain, itype
Email	email, itype, confidence
Hash	md5, itype, confidence
IP	srcip, itype
URL	url, itype

Response

HTTP 202 Accepted

Examples

1. To import private observables of different types:

   curl  example:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H 'Content-Type: application/json' -H 'Authorization: apikey <username>:<api_key>' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {
      "meta":{
         "classification":"private",
         "confidence":60				
      },
      "objects":[
         {
            "srcip":"1.2.3.4",
            "itype":"bot_ip",
            "tags":[
                {
                    "name": "private_tag",
                    "tlp": "red"
                },
   	      {
                    "name": "public_tag",
                    "tlp": "white"
                }
            ],
            "severity":"high"
         },
         {
            "domain":"idfsdszqylwjzq.biz",
            "itype":"mal_domain",
            "severity":"very-high"
         },
         {
            "url":"http://malicious.pl/wp-content/themes/credenza-wp/cr_mss3.exe",
            "itype":"mal_url",
            "severity":"high"
         },
         {
            "email":"email@domain.com",
            "itype":"compromised_email",
            "tags":[
                {
                    "name": "private_tag",
                    "tlp": "red"
                },
   	      {
                    "name": "public_tag",
                    "tlp": "white"
                }
            ],
            "severity":"low"
         },
         {
            "md5":"1d37556b8aeb5cb5fbf08cd5b4790075",
            "itype":"apt_md5",
            "severity":"medium",
            "expiration_ts":"2017-01-26T00:00:00"
         }
      ]
   }

   Python example:

   def import_without_approval(username, api_key):
       auth = 'apikey {}:{}'.format(username, api_key)
       headers = {'Authorization': auth}
       url = "https://api.threatstream.com/api/v2/intelligence/"
       payload = {
           "meta": {
           "confidence": 60,
           "allow_unresolved": True,
           "classification": "private"
       },
       "objects": [
           {
               "value": ""msfbckupsc.com",
               "itype": ""apt_domain",
               "severity": "high",
               "tags": [{"name": "private_tag", "tlp": "red"}]
           },
           {
               "value": "106.210.164.198",
               "itype": "mal_ip",
               "severity": "high"
           }
       ]
   }
   response = requests.patch(url, headers=headers, json=payload)
   print (response.status_code)
   print (response.content)

2. To import an IP address with the minimum required fields:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/?' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {  
      "objects":[  
         {  
            "srcip":"5.253.63.134",
            "itype":"bot_ip"
         }
      ]
   }

3. To import an email address with one private and one public tag:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {
      "meta":{
         "classification":"public",
         "tags":[
            {
               "name":"private_tag",
               "tlp":"red"
            },
            {
               "name":"public_tag",
               "tlp":"white"
            }
         ]
      },
      "objects":[
         {
            "email":"email@test.com",
            "itype":"apt_email"
         }
      ]
   }

4. To import an email address with the minimum required fields and globally configured classification:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {  
      "meta":{  
         "classification":"private"
      },
      "objects":[  
         {  
            "email":"joe@example.com",
            "itype":"mal_email"
         }
      ]
   }

5. To import a domain and use the specified confidence score entirely:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {
    "meta":{  
      "source_confidence_weight":100
   },
   "objects":[  
      {  
         "domain":"www.example.com",
         "itype":"apt_domain",
         "confidence":99
      }
   ]
   }

6. To import IP addresses with confidence specified globally and per observable:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json' --data @/<folder_path>/indicators.json

   where indicators.json contains the following data:

   {  
      "meta":{  
         "confidence":100
      },
      "objects":[  
         {  
            "srcip":"345.678.45.7",
            "itype":"mal_ip",
            "confidence":50
         },
         {  
            "srcip":"322.609.78.33",
            "itype":"apt_ip"
         }
      ]
   }

   In the above example, the confidence value specified for the first observable overrides the globally specified confidence value.